<!DOCTYPE html>

<html lang="en" data-content_root="../">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />

    <title>Getting started with Pytch development &#8212; Pytch  documentation</title>
    <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=03e43079" />
    <link rel="stylesheet" type="text/css" href="../_static/classic.css?v=36340f97" />
    <link rel="stylesheet" type="text/css" href="../_static/css/pytch-classic.css?v=0321735e" />
    
    <script src="../_static/documentation_options.js?v=7f41d439"></script>
    <script src="../_static/doctools.js?v=9bcbadda"></script>
    <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
    
    <link rel="icon" href="../_static/favicon.ico"/>
    <link rel="author" title="About these documents" href="../about.html" />
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="Overview of Pytch design" href="design-overview.html" />
    <link rel="prev" title="Developer documentation" href="../developer.html" /> 
  </head><body>
<div class="NavBar">
  <a href="../../app/"><h1>Pytch</h1></a>
  <ul>
    <a href="https://pytch.scss.tcd.ie/"><li>About Pytch</li></a>
    <a href="../index.html"><li>Help</li></a>
    <a href="../../app/tutorials/"><li>Tutorials</li></a>
    <a href="../../app/my-projects/"><li>My projects</li></a>
  </ul>
</div>
<div class="warning-work-in-progress">
  <p>These help pages are incomplete — we are working on it!</p>
</div>
  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <section id="getting-started-with-pytch-development">
<h1>Getting started with Pytch development<a class="headerlink" href="#getting-started-with-pytch-development" title="Link to this heading">¶</a></h1>
<p>This section explains how to get a development environment set up to
work on Pytch itself.</p>
<section id="requirements">
<h2>Requirements<a class="headerlink" href="#requirements" title="Link to this heading">¶</a></h2>
<dl class="simple">
<dt>Git</dt><dd><p>For fetching and working with the source code and related files.</p>
</dd>
<dt>Python 3</dt><dd><p>The build tools, for example for building tutorials, are based on
version 3 of Python.  Note that on macOS, you need to have run the
<code class="docutils literal notranslate"><span class="pre">Install</span> <span class="pre">Certificates</span></code> command, as is suggested by the Python
installer, to ensure that the Python’s package installer <code class="docutils literal notranslate"><span class="pre">pip</span></code> can
make secure connections.  The command <code class="docutils literal notranslate"><span class="pre">python</span></code> must launch Python
3 — on Ubuntu, you can install the package <code class="docutils literal notranslate"><span class="pre">python-is-python3</span></code> to
achieve this.</p>
</dd>
<dt>Poetry</dt><dd><p>For managing Python projects and their dependencies.  See <a class="reference external" href="https://python-poetry.org/docs/#installation">its web
page</a> for
installation instructions.  <strong>You might have to manually update
your</strong> <code class="docutils literal notranslate"><span class="pre">PATH</span></code><strong>, for example by adding a line to your</strong>
<code class="docutils literal notranslate"><span class="pre">.bashrc</span></code> <strong>file.</strong></p>
</dd>
<dt>Node.js</dt><dd><p>For building the Skulpt-based VM, and the webapp.  Pytch is
developed using the v18 Long Term Support release of Node.js.  The
<code class="docutils literal notranslate"><span class="pre">npm</span></code> package manager is also required, which usually comes
bundled with Node.js.  Your operating system might come with
different versions of <code class="docutils literal notranslate"><span class="pre">node</span></code> and/or <code class="docutils literal notranslate"><span class="pre">npm</span></code>.  A convenient way to
manage multiple <code class="docutils literal notranslate"><span class="pre">node</span></code>/<code class="docutils literal notranslate"><span class="pre">npm</span></code> versions on your machine is to use
<a class="reference external" href="https://github.com/nvm-sh/nvm">the nvm tool</a>.  After installing
<code class="docutils literal notranslate"><span class="pre">nvm</span></code>, you can do <code class="docutils literal notranslate"><span class="pre">nvm</span> <span class="pre">install</span> <span class="pre">v18</span></code> to set up the appropriate
version of node.</p>
</dd>
<dt>Docker</dt><dd><p>Optional, for <a class="reference internal" href="../build-tools/makesite/testing-deployment-zipfile.html#testing-deployment-zipfile"><span class="std std-ref">easy testing of a built
zipfile</span></a>.</p>
</dd>
<dt>The <code class="docutils literal notranslate"><span class="pre">tmux</span></code> terminal multiplexer</dt><dd><p>The dev-server script requires <code class="docutils literal notranslate"><span class="pre">tmux</span></code>, which is available for
Linux and Mac machines.  It is also available on Windows, under the
Windows Subsystem for Linux (<a class="reference internal" href="#developing-on-windows"><span class="std std-ref">see below</span></a>).</p>
</dd>
<dt>GNU <code class="docutils literal notranslate"><span class="pre">coreutils</span></code></dt><dd><p>The build scripts use <code class="docutils literal notranslate"><span class="pre">realpath</span></code> from GNU <code class="docutils literal notranslate"><span class="pre">coreutils</span></code>.  Most
Linux-based systems will install these tools by default.  On macOS
you may need to run <code class="docutils literal notranslate"><span class="pre">brew</span> <span class="pre">install</span> <span class="pre">coreutils</span></code>.</p>
</dd>
</dl>
<p>(This list might be incomplete; please let us know of any gaps.)</p>
</section>
<section id="source-code">
<h2>Source code<a class="headerlink" href="#source-code" title="Link to this heading">¶</a></h2>
<p>Pytch source code is available on GitHub, organised into git
submodules.  The most convenient way to work with it is via the
superproject:</p>
<ul class="simple">
<li><p><a class="reference external" href="https://github.com/pytchlang/pytch-releases/">pytch-releases on GitHub</a></p></li>
</ul>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>If you are developing on a Windows machine, see
<a class="reference internal" href="#developing-on-windows"><span class="std std-ref">Developing on Windows</span></a> below for suggestions.</p>
</div>
<p>To start work on developing Pytch itself, clone this project, and run
the top-level <code class="docutils literal notranslate"><span class="pre">develop.sh</span></code> script.  This will first initialise and
update the submodules’ content, and will appear to be doing nothing
for a short while.  You should then see messages indicating progress,
finishing with a suggestion to run a <code class="docutils literal notranslate"><span class="pre">dev-server.sh</span></code> script.</p>
<p>You only need to run <code class="docutils literal notranslate"><span class="pre">develop.sh</span></code> once.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">dev-server.sh</span></code> script should launch various webservers, and
launch a browser running the webapp.  This should support live reload,
so if you make a small visible change to the UI, for example changing
a button’s text, it should be reflected in the browser within a couple
of seconds of saving the file from your editor/IDE.</p>
<p>To exit, type <code class="docutils literal notranslate"><span class="pre">Ctrl-C</span></code> repeatedly until you’re back at your shell
prompt.</p>
<p>By default, the development webserver listens for connections from
other machines on your local network.  This can be useful in some
settings, but in other settings you might prefer to only allow
connections from your development machine.  If so, you can launch the
<code class="docutils literal notranslate"><span class="pre">dev-server.sh</span></code> script with the environment variable <code class="docutils literal notranslate"><span class="pre">HOST</span></code> set to
<code class="docutils literal notranslate"><span class="pre">localhost</span></code>.  This can be done with the shell command</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span><span class="nv">HOST</span><span class="o">=</span>localhost<span class="w"> </span>./pytch-build/makesite/local-server/dev-server.sh
</pre></div>
</div>
<p>(assuming your shell is currently in the top-level <code class="docutils literal notranslate"><span class="pre">pytch-releases</span></code>
directory).</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>If you get an error <code class="docutils literal notranslate"><span class="pre">duplicate</span> <span class="pre">session:</span> <span class="pre">pytchdev</span></code> when trying to
run the <code class="docutils literal notranslate"><span class="pre">dev-server.sh</span></code> script, this is probably because you
closed the terminal window running a previous invocation of the
<code class="docutils literal notranslate"><span class="pre">dev-server.sh</span></code> script without typing <code class="docutils literal notranslate"><span class="pre">Ctrl-C</span></code>s.  This means
the <code class="docutils literal notranslate"><span class="pre">tmux</span></code> session is still running.  To re-attach to that
session, run <code class="docutils literal notranslate"><span class="pre">tmux</span> <span class="pre">attach</span> <span class="pre">-t</span> <span class="pre">pytchdev</span></code>.  To start a new session,
run <code class="docutils literal notranslate"><span class="pre">tmux</span> <span class="pre">kill-session</span> <span class="pre">-t</span> <span class="pre">pytchdev</span></code> and then run the
<code class="docutils literal notranslate"><span class="pre">dev-server.sh</span></code> script again.</p>
</div>
</section>
<section id="developing-on-linux">
<h2>Developing on Linux<a class="headerlink" href="#developing-on-linux" title="Link to this heading">¶</a></h2>
<p>If, on Ubuntu, you encounter strange errors when trying to install
<code class="docutils literal notranslate"><span class="pre">nvm</span></code>, check whether <code class="docutils literal notranslate"><span class="pre">curl</span></code> has been installed as a Snap.  We have
seen this lead to the situation where <code class="docutils literal notranslate"><span class="pre">curl</span></code> doesn’t have permission
to write files.  Installing <code class="docutils literal notranslate"><span class="pre">curl</span></code> via <code class="docutils literal notranslate"><span class="pre">apt</span></code> is recommended.</p>
</section>
<section id="developing-on-macos">
<h2>Developing on macOS<a class="headerlink" href="#developing-on-macos" title="Link to this heading">¶</a></h2>
<p>The preferred way to get a definite version of Python on Mac seems to
be to use <code class="docutils literal notranslate"><span class="pre">homebrew</span></code>:</p>
<ul class="simple">
<li><p>Install the <code class="docutils literal notranslate"><span class="pre">.pkg</span></code> file available from <a class="reference external" href="https://github.com/Homebrew/brew/releases/latest">homebrew’s GitHub
releases page</a>.
This installs everything under <code class="docutils literal notranslate"><span class="pre">/opt/homebrew</span></code>, so you have to add
<code class="docutils literal notranslate"><span class="pre">/opt/homebrew/bin</span></code> to the front of your <code class="docutils literal notranslate"><span class="pre">PATH</span></code>.</p></li>
<li><p>Do <code class="docutils literal notranslate"><span class="pre">brew</span> <span class="pre">install</span> <span class="pre">python3</span></code>.  This prints instructions about the
directory to which a <code class="docutils literal notranslate"><span class="pre">python</span></code> link has been installed.  Add that
directory to the front of your <code class="docutils literal notranslate"><span class="pre">PATH</span></code>.</p></li>
<li><p>Check that <code class="docutils literal notranslate"><span class="pre">python</span></code> at a command prompt gives you the expected
installation of Python 3.</p></li>
</ul>
</section>
<section id="developing-on-windows">
<span id="id1"></span><h2>Developing on Windows<a class="headerlink" href="#developing-on-windows" title="Link to this heading">¶</a></h2>
<p>The preferred way to do development work on Pytch within Windows is to
do so under the Windows Subsystem for Linux.  Follow <a class="reference external" href="https://learn.microsoft.com/en-us/windows/wsl/install">Microsoft’s
instructions</a>
to set up what amounts to an Ubuntu virtual machine inside your
Windows machine.</p>
<p>This sometimes involves a reboot.</p>
<p>(If you encounter an error like</p>
<blockquote>
<div><p>Error: 0xc03a001a The requested operation could not be completed due
to a virtual disk system limitation.  Virtual hard disk files must be
uncompressed and unencrypted and must not be sparse.</p>
</div></blockquote>
<p>then <a class="reference external" href="https://utf9k.net/blog/wsl2-vhd-issue/">this blog post</a>
describes how the author solved it.)</p>
<p>Once you have WSL set up, within your Ubuntu distribution run:</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>sudo<span class="w"> </span>apt<span class="w"> </span>update
sudo<span class="w"> </span>apt<span class="w"> </span>install<span class="w"> </span>zip<span class="w"> </span>unzip
</pre></div>
</div>
<p>(If the first of these commands gives errors involving</p>
<blockquote>
<div><p>Temporary failure resolving archive.ubuntu.com</p>
</div></blockquote>
<p>then one possible cause is that your WSL set-up does not have its DNS
configured correctly.  <a class="reference external" href="https://superuser.com/questions/1533291/how-do-i-change-the-dns-settings-for-wsl2">This StackExchange superuser post</a>
describes the process for using a public DNS server like Cloudflare’s
<code class="docutils literal notranslate"><span class="pre">1.1.1.1</span></code>, which might fix the problem.)</p>
<p>Then install <code class="docutils literal notranslate"><span class="pre">nvm</span></code> following the instructions in <a class="reference external" href="https://github.com/nvm-sh/nvm">its README</a> and install node v18 by running</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>nvm<span class="w"> </span>install<span class="w"> </span>v18
</pre></div>
</div>
<p>Once this is all done, you should be able to follow the main
instructions above, starting with cloning the <code class="docutils literal notranslate"><span class="pre">pytch-releases</span></code>
super-project.</p>
<p>If you would like to use Microsoft’s VSCode for development work, you
can run your native Windows VSCode, and access your Ubuntu files using
a Windows pathname starting <code class="docutils literal notranslate"><span class="pre">\\wsl$\Ubuntu\home\your_username\</span></code>.</p>
<section id="home-directories">
<h3>Home directories<a class="headerlink" href="#home-directories" title="Link to this heading">¶</a></h3>
<p>Be aware that your Windows home directory and your Ubuntu home
directory are different.  For example, when setting up SSH keys, you
need to ensure you are working within your <em>Ubuntu</em> home directory.
After launching WSL, you can use the shell command</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span><span class="nb">cd</span>
</pre></div>
</div>
<p>to change to your Ubuntu home directory.</p>
</section>
</section>
</section>


            <div class="clearer"></div>
          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="Main">
        <div class="sphinxsidebarwrapper"><ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../webapp/user/index.html">Using the Pytch web app</a></li>
<li class="toctree-l1"><a class="reference internal" href="../vm/user/index.html">Writing Pytch programs</a></li>
<li class="toctree-l1"><a class="reference internal" href="../about.html">About Pytch</a></li>
<li class="toctree-l1"><a class="reference internal" href="../contact.html">Contact</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../developer.html">Developer documentation</a><ul class="current">
<li class="toctree-l2 current"><a class="current reference internal" href="#">Development setup</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#requirements">Requirements</a></li>
<li class="toctree-l3"><a class="reference internal" href="#source-code">Source code</a></li>
<li class="toctree-l3"><a class="reference internal" href="#developing-on-linux">Developing on Linux</a></li>
<li class="toctree-l3"><a class="reference internal" href="#developing-on-macos">Developing on macOS</a></li>
<li class="toctree-l3"><a class="reference internal" href="#developing-on-windows">Developing on Windows</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="design-overview.html">Design overview</a></li>
<li class="toctree-l2"><a class="reference internal" href="../vm/developer/index.html">VM</a></li>
<li class="toctree-l2"><a class="reference internal" href="../webapp/developer/index.html">Webapp</a></li>
<li class="toctree-l2"><a class="reference internal" href="../medialib/developer/index.html">Media library</a></li>
<li class="toctree-l2"><a class="reference internal" href="index.html">Website</a></li>
<li class="toctree-l2"><a class="reference internal" href="../build-tools/index.html">Tools</a></li>
<li class="toctree-l2"><a class="reference internal" href="../source-build.html">Source and build information</a></li>
<li class="toctree-l2"><a class="reference internal" href="../releases/changelog.html">Changelog</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../legal/index.html">Legal information</a></li>
</ul>
<div class="docs-home-link"><hr>
  <ul>
    <li>
      <a href="../index.html">Pytch help home</a>
    <li>
  </ul>
</div>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
  </body>
</html>